home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / DELPHI32 / DEBUG / STAKWK10 / STAKWK10.ZIP / STAKWALK.TXT < prev    next >
Text File  |  1996-05-19  |  8KB  |  162 lines
  1. StackWalker 1.0:  Delphi 2.0 debugger helper.
  2. Copyright (c) 1996, D.J. Murdoch
  3.  
  4.  
  5.   These units (STAKWALK and STAKLOW) help with the problem of exceptions
  6.   occurring in the run-time library in Borland's Delphi 2.0:  the
  7.   debugger often can't find where in your code the error was triggered.
  8.  
  9.   The problem is that when an exception occurs, the debugger tries to
  10.   walk up the stack until it finds a return address in your source code.
  11.   However, sometimes it can't walk up the stack, and so it can't find
  12.   the error.  (This might be related to whether you have stack frames
  13.   turned on, but sometimes doing that is not enough.)
  14.  
  15.   What I did to fix this in StackWalker was to install an exception
  16.   handler that would look at *every* value on the stack, trying to find
  17.   one that appears to be a return address to code with source.  It does
  18.   this by reading the .MAP file to figure out source addresses, and then
  19.   just comparing everything on the stack to those until it turns
  20.   something up.
  21.  
  22.   This procedure is definitely not bulletproof.  There are lots of
  23.   reasons to have addresses on the stack that aren't return addresses;
  24.   if you do, StackWalker will give false messages.  However, getting a
  25.   few false addresses mixed in with the real ones is better than getting no
  26.   information at all.
  27.  
  28.   To use it:
  29.  
  30.   1. Set the detailed map file linker option on.  This is in the
  31.      Project|Options|Linker page.  StackWalker uses the .MAP file to
  32.      figure out what return addresses correspond to code. If it can't
  33.      find the .MAP file in the same directory as the executable, or
  34.      can't find the line number records in the .MAP file, it gives a
  35.      warning and makes wild guesses, which give so many false alarms
  36.      that it'll soon convince you to generate the .MAP file.
  37.  
  38.   2. Set the $D+ option on for every unit where you want to see the
  39.      errors.  StackWalker won't show addresses in units compiled $D-
  40.      (unless you forgot to make the .MAP file).
  41.  
  42.   3. Link one of the StackWalker units into your code.  There are 2 ways
  43.      to do this:
  44.      a) If you've got a regular Delphi application, then add
  45.         StakWalk to the project.  It will automatically install all the
  46.         hooks to get things working.
  47.   OR b) In a console mode application or other application that doesn't
  48.         use VCL, add StakLow to the project or to a Uses clause
  49.         somewhere. It will install itself as the default exception
  50.         handler.  (This doesn't work in a VCL application, because the
  51.         default handler never gets called.) You won't get the helpful
  52.         dialog that StakWalk gives you, but it should still give you the
  53.         same information.
  54.  
  55.         If you have your own default exception handler, you might find
  56.         that StakLow messes it up, or doesn't get activated.  But if
  57.         you've got your own exception handler, you're probably clever
  58.         enough to figure out how to fix this kind of problem.
  59.  
  60.   4. Compile and run your program and do whatever it is that triggers
  61.      the exception.  After the usual unhelpful message pops up telling
  62.      you that an exception happened somewhere (but not telling you
  63.      where), hit F9 to continue running.  At this point StackWalker will
  64.      examine the stack and trigger an exception at every place it thinks
  65.      might be in the call stack.  (You'll likely get a few false alarms.
  66.      If there was a foolproof way to do this, Delphi would do it
  67.      itself).
  68.  
  69.   5. When you've found the place that really caused the trouble, click
  70.      Cancel in the StackWalker dialog (or manually change the value of
  71.      the global variable StopWalker to True) to stop it from walking
  72.      all the way back up the stack.  If you don't do this and let it go
  73.      too far, it'll eventually trigger an exception at the
  74.      "Application.Run" line.  If you keep going past that, you may find
  75.      weird behaviour (e.g. I found once that StackWalker got turned off
  76.      for no apparent reason); I think by that point your program may be
  77.      messed up, so be careful.
  78.  
  79.   You can have a little more control over the behaviour by manually
  80.   setting some of the global variables in the StakLow unit:
  81.  
  82.     WalkerActive: set this to False when you don't need the
  83.      special handling for future exceptions.
  84.  
  85.     StopWalker:  set this to True to stop the current walk.
  86.  
  87.     ContinueFunc:  assign a boolean function to this variable, to
  88.      replace StakWalk's dialog.  It will be called just before the
  89.      exception is triggered, and should return true if you want
  90.      another debug exception generated.
  91.  
  92.  
  93.   You can also make a call to WalkStack at any time to trigger a walk
  94.   through the stack.
  95.  
  96. BUGS:
  97.  
  98.   For reasons I don't understand and don't know how to fix, floating
  99.   point exceptions sometimes mess up StackWalker.  You'll just get the
  100.   regular exception message over and over again, and never find out
  101.   where it was triggered.  If you know how to fix this, please tell me.
  102.  
  103. FILES:
  104.  
  105.   This package contains the following files:
  106.  
  107.     STAKWALK.TXT:   This doc file.
  108.     STAKWALK.PAS:   The high level unit to use to turn on StackWalker.
  109.     STAKWALK.DFM:   The form file for the StackWalker dialog.
  110.     STAKLOW.PAS:    The low level unit used by STAKWALK, or directly if
  111.                     you don't use VCL.
  112.     PROJECT1.DPR, UNIT1.PAS, UNIT1.DFM:   A simple demonstration project.
  113.  
  114. RELEASE HISTORY:
  115.  
  116.   Version 0.1:  Initial release
  117.           0.2:  Forced optimization off in StakLow, so test for stack
  118.                 doesn't get optimized away
  119.           0.3:  Added check for debugger, so you can distribute code to
  120.                 testers but not have the dialog pop up except when they're
  121.                 debugging.
  122.           1.0:  First public release; same as 0.3.
  123.  
  124. LICENSE:
  125.  
  126.   StackWalker is not public domain code.  Its copyright belongs to
  127.   Duncan Murdoch.  You are licensed to use it at no charge, but may not
  128.   sell it or incorporate it into another product without prior written
  129.   permission.  You may not charge more than $1 for the distribution of
  130.   StackWalker.  You may include it in a CDROM compilation provided you
  131.   charge no more than $1 per package in the compilation.  As a courtesy,
  132.   I would appreciate receiving a copy of any CDROM that includes it, but
  133.   this is not a legal requirement.
  134.  
  135.   I do not offer any guarantee or support for StackWalker.  It works at
  136.   a low level, and there may well be conditions that cause it to crash
  137.   your program, Delphi, or Windows.
  138.  
  139.   If StackWalker helps you so much that you want to show your
  140.   appreciation in a monetary way, you may send a contribution in any
  141.   amount to
  142.  
  143.     D.J. Murdoch
  144.     337 Willingdon Ave.
  145.     Kingston, Ontario, Canada
  146.     K7L 4J3
  147.  
  148.   For contributions of $20 (US or Canadian) or more, I'll send you a
  149.   diskette containing the latest version of StackWalker and a collection
  150.   of other utilities that I've written.  Please make payments by US
  151.   dollar cheque drawn on a US bank, Canadian dollar cheque drawn on a
  152.   Canadian bank, or pounds Stirling cheque drawn on a UK bank
  153.   (equivalent to $20 US, if you want the diskette). Unfortunately, I
  154.   can't accept credit cards to handle payments from people from other
  155.   countries.  However, I do have an arrangement with the Public Software
  156.   Library to accept shareware registrations for various programs by
  157.   credit card, and some of those will get you the disk;  write to me for
  158.   details.
  159.  
  160.     Duncan Murdoch
  161.     dmurdoch@mast.queensu.ca
  162.